home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 22
/
Cream of the Crop 22.iso
/
program
/
euphor14.zip
/
LIBRARY.DOC
< prev
next >
Wrap
Text File
|
1996-07-11
|
97KB
|
2,572 lines
Part II - Library Routines
1. Introduction
A large number of library routines are provided. Some are built right into
the interpreter, ex.exe. Others are written in Euphoria and you must include
one of the .e files in euphoria\include to use them. Where this is the case,
the appropriate include file is noted in the "Syntax" part of the description.
Of course an include file need only be included once in your program. The
editor displays in magenta those routines that are built into the interpreter,
ex.exe, and require no include file. You can override the definition of these
built-in routines by defining your own routine with the same name. You will
get a suppressible warning if you do this.
To indicate what kind of object may be passed in and returned, the following
prefixes are used:
x - a general object (atom or sequence)
s - a sequence
a - an atom
i - an integer
fn - an integer used as a file number
st - a string sequence, or single-character atom
An error will result if an illegal argument value is passed to any of these
routines.
2. Routines by Application Area
2.1 Predefined Types
As well as declaring variables with these types, you can also call them
just like ordinary functions, in order to test if a value is a certain
type.
integer - test if an object is an integer
atom - test if an object is an atom
sequence - test if an object is a sequence
2.2 Sequence Manipulation
length - return the length of a sequence
repeat - repeat an object n times to form a sequence of length n
append - add a new element to the end of a sequence
prepend - add a new element to the beginning of a sequence
2.3 Searching and Sorting
compare - compare two objects
find - find an object in a sequence
match - find a sequence as a slice of another sequence
sort - sort the elements of a sequence into ascending order
2.4 Pattern Matching
lower - convert a string to lower case
upper - convert a string to upper case
wildcard_match - match a pattern containing ? and * wildcards
wildcard_file - match a file name against a wild card specification
2.5 Math
These routines can be applied to individual atoms or to sequences of
values. See "Arithmetic Operations on Sequences" in chapter 2 of the
reference manual.
sqrt - calculate the square root of an object
rand - generate random numbers
sin - calculate the sine of an angle
cos - calculate the cosine of an angle
tan - calculate the tangent of an angle
log - calculate the natural logarithm
floor - round down to the nearest integer
remainder - calculate the remainder when a number is divided by another
power - calculate a number raised to a power
2.6 File and Device I/O
To do input or output on a file or device you must first open the file
or device, then use the routines below to read or write to it, then close
the file or device. open() will give you a file number to use as the
first argument of the other I/O routines. Certain files/devices are
opened for you automatically (as text files):
0 - standard input
1 - standard output
2 - standard error
Unless you redirect them on the command line, standard input comes from
the keyboard, standard output and standard error go to the screen. When
you write something to the screen it is written immediately without
buffering. If you write to a file, your characters are put into a buffer
until there are enough of them to write out efficiently. When you close
the file or device, any remaining characters are written out. Input from
files is also buffered. When your program terminates, any files that are
still open will be closed for you automatically.
Note: If a program (written in Euphoria or any other language) has a
file open for writing, and you are forced to reboot your computer for
any reason, you should immediately run CHKDSK or SCANDISK to repair any
damage to the file system that may have occurred.
open - open a file or device
close - close a file or device
print - print a Euphoria object with {,,} to show the structure
? x - shorthand for print(1, x)
printf - formatted print to a file or device
sprintf - formatted print returned as a string sequence
puts - output a string sequence to a file or device
getc - read the next character from a file or device
gets - read the next line from a file or device
get_key - check for key pressed by the user, don't wait
wait_key - wait for user to press a key
get - read the representation of any Euphoria object from a file
value - read the representation of any Euphoria object from a string
seek - move to any character position within an open file
where - report the current character position in an open file
current_dir - return the name of the current directory
dir - return complete info on all files in a directory
2.7 Mouse Support
get_mouse - return mouse "events" (clicks, movements)
mouse_events - select mouse events to watch for
mouse_pointer - display or hide the mouse pointer
2.8 Operating System
time - number of seconds since a fixed point in the past
date - current year, month, day, hour, minute, second etc.
command_line - DOS command-line used to run this program
getenv - get value of an environment variable
system - execute a DOS command line
abort - terminate execution
2.9 Special Machine-dependent routines
machine_func - specialized operations in ex.exe with return value
machine_proc - specialized operations in ex.exe - no return value
2.10 Debugging
trace - dynamically turns tracing on or off
2.11 Graphics & Sound
clear_screen - clear the screen - text or graphics
position - set cursor line and column
get_position - return cursor line and column
graphics_mode - select a new graphics (or text) mode
video_config - return parameters of current graphics mode
scroll - scroll text screen up or down
wrap - control line wrap at right edge of screen
cursor - select cursor shape
text_color - set foreground text color
bk_color - set background color for text and graphics
palette - change color for one color number
all_palette - change color for all color numbers
text_rows - set number of lines on text screen
pixel - set color of a pixel or set of pixels
get_pixel - read color of a pixel or set of pixels
draw_line - connect a series of graphics points with a line
polygon - draw an n-sided figure
ellipse - draw an ellipse (circle)
sound - make a sound on the PC speaker
read_bitmap - read a bitmap file and return a sequence of pixels
save_image - save a rectangular region from a graphics screen
save_text_image - save a rectangular region from a text screen
display_image - display an image on the graphics screen
display_text_image - display an image on the text screen
get_active_page - return the page currently being written to
set_active_page - change the page currently being written to
get_display_page - return the page currently being displayed
set_display_page - change the page currently being displayed
2.12 Machine Level Interface
With this low-level machine interface you can read and write to memory.
You can also set up your own 386+ machine language routines and call
them. The usual guarantee that Euphoria will protect you from machine-
level errors does *not* apply when you use these routines. If you happen
to reference a bad address, it will likely be caught by the Causeway DOS
extender and you'll see an error message on the screen plus a dump of
machine-level information in the file CW.ERR.
Most Euphoria programmers will never use this interface, but it is
important because it makes it possible to get into every nook and cranny
of the hardware and operating system. For those with very specialized
applications this could be crucial.
Machine code routines can be written by hand, or taken from the
disassembled output of a compiler for C or some other language.
Remember that your machine code will be running in 32-bit protected
mode. See demo\callmach.ex for an example.
peek - read one or more bytes from memory
poke - write one or more bytes to memory
call - call a machine language routine
dos_interrupt - call a DOS software interrupt routine
allocate - allocate a block of memory
free - deallocate a block of memory
allocate_low - allocate a block of low memory (address less than 1Mb)
free_low - free a block allocated with allocate_low
int_to_bytes - convert an integer to 4 bytes
bytes_to_int - convert 4 bytes to an integer
int_to_bits - convert an integer to a sequence of bits
bits_to_int - convert a sequence of bits to an integer
set_rand - set the random number generator so it will generate
a repeatable series of random numbers
use_vesa - force the use of the VESA graphics standard
crash_message - specify a message to be printed if Euphoria detects an
an error in your program
3. Alphabetical Listing of all Routines
──────────────────────────────────────<?>───────────────────────────────────────
Syntax: ? x
Description: This is just a shorthand way of saying: print(1, x)
i.e. printing the value of an expression to the standard output.
Example:
? {1, 2} + {3, 4}
would display {4, 6}.
Comments: ? differs slightly from print() since it will add new-lines to
make the output more readable on your screen or wherever you
have directed standard output.
See Also: print
────────────────────────────────────<abort>─────────────────────────────────────
Syntax: abort(a)
Description: Abort execution of the program. The argument a is an integer
status value to be returned to the operating system. A value of 0
generally indicates successful completion of the program. Other
values can indicate various kinds of errors. DOS batch (.bat)
programs can read this value using the errorlevel feature.
Comments: abort() is useful when a program is many levels deep in
subroutine calls, and execution must end immediately, perhaps
due to a severe error that has been detected.
Normally ex.exe returns an exit status code of 0. If your program
fails with a Euphoria-detected compile-time or run-time error
then a code of 1 is returned.
Example:
if x = 0 then
puts(ERR, "can't divide by 0 !!!\n")
abort(1)
else
z = y / x
end if
See Also: crash_message
─────────────────────────────────<all_palette>──────────────────────────────────
Syntax: include graphics.e
all_palette(s)
Description: Specify new color intensities for the entire set of colors in the
current graphics mode. s is a sequence of the form:
{{r,g,b}, {r,g,b}, ... {r,g,b}}
Each element specifies a new color intensity {red, green, blue}
for the corresponding color number, starting with color number 0.
The values for red, green and blue must be in the range 0 to 63.
Comments: This executes much faster than if you were to use palette() to
set the new color intensities one by one. This procedure can
be used with read_bitmap() to quickly display a picture on the
screen.
Example Program: demo\bitmap.ex
See Also: palette, read_bitmap, video_config, graphics_mode
───────────────────────────────────<allocate>───────────────────────────────────
Syntax: include machine.e
a = allocate(i)
Description: Allocate i contiguous bytes of memory. Return the address of the
block of memory, or return 0 if the memory can't be allocated.
Example: buffer = allocate(100)
for i = 0 to 99 do
poke(buffer+i, 0)
end for
See Also: free, allocate_low, peek, poke, call
─────────────────────────────────<allocate_low>─────────────────────────────────
Syntax: include machine.e
i2 = allocate_low(i1)
Description: Allocate i1 contiguous bytes of low memory, i.e. conventional
memory with an address below 1 megabyte. Return the address
of the block of memory, or return 0 if the memory can't be
allocated.
Comment: Some DOS software interrupts require that you pass one or
more addresses in registers. These addresses must be
conventional memory addresses for DOS to be able to read or
write to them.
Example Program: demo\dosint.ex
See Also: dos_interrupt, free_low, allocate, peek, poke
────────────────────────────────────<append>────────────────────────────────────
Syntax: s2 = append(s1, x)
Description: Create a new sequence identical to s1 but with x added on the end
as the last element. The length of s2 will be length(s1) + 1.
Comments: If x is an atom this is equivalent to s2 = s1 & x. If x is a
sequence it is not equivalent.
The extra storage is allocated automatically and very
efficiently with Euphoria's dynamic storage allocation.
The case where s1 and s2 are actually the same variable
(as in Example 1 below) is highly optimized.
Example 1: You can use append to dynamically grow a sequence, e.g.
sequence x
x = {}
for i = 1 to 10 do
x = append(x, i)
end for
-- x is now {1,2,3,4,5,6,7,8,9,10}
Example 2: Any kind of Euphoria object can be appended to a sequence, e.g
sequence x, y, z
x = {"fred", "barney"}
y = append(x, "wilma")
-- y is now {"fred", "barney", "wilma"}
z = append(append(y, "betty"), {"bam", "bam"})
-- z is now {"fred", "barney", "wilma", "betty", {"bam", "bam"}}
See Also: prepend, concatenation (&) and sequence-formation {,,} operators
in refman.doc
─────────────────────────────────────<atom>─────────────────────────────────────
Syntax: i = atom(x)
Description: Return 1 if x is an atom else return 0.
Comments: This serves to define the atom type. You can also call it
like an ordinary function to determine if an object is an
atom.
Example 1:
atom a
a = 5.99
Example 2:
line = gets(0)
if atom(line) then
puts(SCREEN, "end of file\n")
end if
See Also: sequence
─────────────────────────────────<bits_to_int>──────────────────────────────────
Syntax: include machine.e
a = bits_to_int(s)
Description: Convert a sequence of binary 1's and 0's into a positive
number. The least-significant bit is s[1].
Comments: If you print s the bits will appear in "reverse" order, but
it is convenient to have increasing subscripts access bits of
increasing significance.
Example: a = bits_to_int({1,1,1,0,1})
-- a is 23 (binary 10111)
See Also: int_to_bits, and/or/not of sequences in refman.doc
───────────────────────────────────<bk_color>───────────────────────────────────
Syntax: include graphics.e
bk_color(i)
Description: Set the background color. In graphics modes the whole screen is
affected immediately. In text modes any new characters that you
print will have the new background color.
Comments: The various colors are defined as constants in graphics.e
To restore the original background color when your program
finishes, e.g. 0 - BLACK, you must call bk_color(0), and then if
you are at the bottom line of the screen, ready to scroll up,
you may have to actually print something before terminating your
program. Printing '\n' may be enough.
Example: bk_color(BLACK)
See Also: text_color
─────────────────────────────────<bytes_to_int>─────────────────────────────────
Syntax: include machine.e
a = bytes_to_int(s)
Description: Convert a 4-element sequence of byte values to an atom.
The elements of s are in the order expected for a 32-bit
integer on the 386, i.e. least significant byte first.
Comments: The result could be greater than the integer type allows,
so you should assign it to an atom.
s would normally contain positive values that have been read
using peek() from 4 consecutive memory locations.
Example: atom int32
int32 = bytes_to_int({37,1,0,0})
-- int32 is 37 + 256*1 = 293
See Also: int_to_bytes, bits_to_int, peek, poke
─────────────────────────────────────<call>─────────────────────────────────────
Syntax: call(a)
Description: Call a machine language routine that starts at address a. This
routine must execute a RET instruction #C3 to return control
to Euphoria. The routine should save and restore any registers
that it uses.
Comments: You can allocate a block of memory for the routine and then poke
in the bytes of machine code. You might allocate other blocks of
memory for data and parameters that the machine code can operate
on. The addresses of these blocks could be poked into the
machine code.
Example Program: see demo\callmach.ex
See Also: allocate, free, peek, poke
─────────────────────────────────<clear_screen>─────────────────────────────────
Syntax: clear_screen()
Description: Clear the screen using the current background color (may be set
by bk_color()).
Comments: This works in all text and graphics modes.
See Also: bk_color, graphics_mode
────────────────────────────────────<close>─────────────────────────────────────
Syntax: close(fn)
Description: Close a file or device and flush out any still-buffered
characters.
Comments: Any still-open files will be closed automatically when your
program terminates.
See Also: open
────────────────────────────────<command_line>──────────────────────────────────
Syntax: s = command_line()
Description: Return a sequence of strings, where each string is a word from
the command line that started your program. The first word will
be the path to either the Euphoria executable, ex.exe or to
your bound .exe file. The next word is either the name of your
Euphoria .ex file, or the path to your bound .exe file. After
that will come any extra words typed by the user. You can use
these words in your program.
Comments: Euphoria (ex.exe) does not use any command line options. You
are free to use any options for your own program.
If you bind your program you will find that all command line
arguments remain the same, except for the first two, even
though your user no longer types "ex".
Example 1: -- The user types: ex myprog myfile.dat 12345
cmd = command_line()
-- cmd will be: {"C:\EUPHORIA\BIN\EX.EXE",
"myprog",
"myfile.dat",
"12345"}
Example 2: -- Your program is bound with the name "myprog.exe"
-- and is stored in the directory c:\myfiles
-- The user types: myprog myfile.dat 12345
cmd = command_line()
-- cmd will be: {"C:\MYFILES\MYPROG.EXE",
"C:\MYFILES\MYPROG.EXE", -- spacer
"myfile.dat",
"12345"}
-- Note that all arguments remain the same as Example 1
-- except for the first two. The second argument is always
-- the same as the first and is inserted to keep the numbering
-- of the subsequent arguments the same, whether your program
-- is bound as a .exe or not.
See Also: getenv
───────────────────────────────────<compare>────────────────────────────────────
Syntax: i = compare(x1, x2)
Description: Return 0 if objects x1 and x2 are identical, 1 if x1 is greater
than x2, -1 if x1 is less than x2. Atoms are considered to be
less than sequences. Sequences are compared "alphabetically"
starting with the first element until a difference is found.
Example 1: x = compare({1,2,{3,{4}},5}, {2-1,1+1,{3,{4}},6-1})
-- identical, x is 0
Example 2: if compare("ABC", "ABCD") < 0 then -- -1
-- will be true: ABC is "less" because it is shorter
end if
See Also: equals (=) operator in refman.doc
─────────────────────────────────────<cos>──────────────────────────────────────
Syntax: x2 = cos(x1)
Description: Return the cosine of x1, where x1 is in radians.
Comments: This function may be applied to an atom or to all elements
of a sequence.
Example: x = cos({.5, .6, .7})
-- x is {0.8775826, 0.8253356, 0.7648422}
See Also: sin, tan, log, sqrt
────────────────────────────────<crash_message>─────────────────────────────────
Syntax: include machine.e
crash_message(s)
Description: Specify a string, s, to be printed on the screen in the event
that Euphoria must stop your program due to a compile-time or
run-time error.
Comments: Normally Euphoria prints a diagnostic message such as
"syntax error" or "divide by zero" on the screen, as well as
dumping debugging information into "ex.err". Euphoria's error
messages will not be meaningful for your users unless they
happen to be Euphoria programmers. By calling crash_message()
you can control the message that will appear on the screen.
Debugging information will still be stored in ex.err. You won't
lose any information by doing this.
s may contain '\n', new-line characters so your message can
span several lines on the screen.
You can call crash_message() as many times as you like from
different parts of your program. The message specified by the
last call will be the one displayed.
Your crash message will always be displayed if a compile-time
error (syntax, undeclared variable etc.) occurs. In the case of
a run-time error (subscript out of bounds, uninitialized
variable, divide by zero etc.) your program must be executed
by the Complete Edition EX.EXE, or have been bound using
the Complete Edition PDEX.EXE, or be under 300 statements.
Example: crash_message("An unexpected error has occurred!\n" &
"Please contact john_doe@whoops.com\n" &
"Do not delete the file \"ex.err\".\n")
See Also: abort
Debugging section of refman.doc
─────────────────────────────────<current_dir>──────────────────────────────────
Syntax: include file.e
s = current_dir()
Description: Return the name of the current working directory.
Example:
sequence s
s = current_dir()
-- s would have "C:\EUPHORIA\DOC" if you were in that directory
See Also: dir, getenv
────────────────────────────────────<cursor>────────────────────────────────────
Syntax: include graphics.e
cursor(i)
Description: Select a style of cursor. graphics.e contains:
global constant NO_CURSOR = #2000,
UNDERLINE_CURSOR = #0607,
THICK_UNDERLINE_CURSOR = #0507,
HALF_BLOCK_CURSOR = #0407,
BLOCK_CURSOR = #0007
The second and fourth hex digits (from the left) determine the
top and bottom rows of pixels in the cursor. The first digit
controls whether the cursor will be visible or not. For example,
#0407 turns on the 4th through 7th rows.
Example: cursor(BLOCK_CURSOR)
─────────────────────────────────────<date>─────────────────────────────────────
Syntax: s = date()
Description: Return a sequence with the following information:
{ year (since 1900),
month (January = 1),
day (day of month, starting at 1),
hour (0 to 23),
minute (0 to 59),
second (0 to 59),
day of the week (Sunday = 1),
day of the year (January 1st = 1) }
Example: now = date()
-- now has: {95,3,24,23,47,38,6,83}
-- i.e. Friday March 24, 1995 at 11:47:38pm, day 83 of the year
See Also: time
─────────────────────────────────────<dir>──────────────────────────────────────
Syntax: include file.e
x = dir(st)
Description: Return directory information for the file or directory named by
st. If there is no file or directory with this name then -1 is
returned.
This information is similar to what you would get from the DOS
DIR command. A sequence is returned where each element is a
sequence that describes one file or subdirectory.
If st names a directory you may have entries for "." and "..",
just as with the DOS DIR command. If st names a file then x will
have just one entry, i.e. length(x) will be 1.
Each entry contains the name, attributes and file size as well
as the year, month, day, hour, minute and second of the last
modification. You can refer to the elements of an entry with
the following constants defined in file.e:
global constant
D_NAME = 1,
D_ATTRIBUTES = 2,
D_SIZE = 3,
D_YEAR = 4,
D_MONTH = 5,
D_DAY = 6,
D_HOUR = 7,
D_MINUTE = 8,
D_SECOND = 9
The attributes element is a string sequence containing
characters chosen from:
d - directory
r - read only file
h - hidden file
s - system file
v - volume-id entry
a - archive file
A normal file without special attributes would just have an empty
string, "", in this field.
Comments: The top level directory, e.g. c:\ does not have "." or ".."
entries.
This function is often used just to test if a file or
directory exists.
Under Windows 95, st can have a long file or directory name
anywhere in the path.
The file name returned in D_NAME will be a standard DOS 8.3 name,
even on Windows 95 or Windows NT. A new long-filename element
may be added in a future release of Euphoria.
Example:
d = dir(current_dir())
-- d might have:
{
{".", "d", 0 1994, 1, 18, 9, 30, 02},
{"..", "d", 0 1994, 1, 18, 9, 20, 14},
{"fred", "ra", 2350, 1994, 1, 22, 17, 22, 40},
{"sub", "d" , 0, 1993, 9, 20, 8, 50, 12}
}
d[3][D_NAME] would be "fred"
Example Programs: bin\search.ex, install.ex
See Also: wildcard_file, current_dir, open
────────────────────────────────<display_image>─────────────────────────────────
Syntax: include image.e
display_image(s1, s2)
Description: Display at point s1 on the screen the 2-d sequence of pixels
contained in s2. s1 is a two-element sequence {x, y}. s2 is a
sequence of sequences, where each sequence is one horizontal
line of pixel colors to be displayed. The first pixel of the
first sequence is displayed at s1. It is the top-left pixel.
All other pixels appear to the right or below of this point.
Comments: s2 might be the result of a previous call to save_image(), or
read_bitmap(), or it could be something you have created.
You could use save_image/display_image in a graphical user
interface, to allow "pop-up" dialog boxes, and drop-down menus
to appear and disappear without losing what was previously on
the screen.
The sequences (rows) of the image do not have to all be the
same length.
Example: display_image({20,30}, {{1,5,9},
{2,4},
{1,0,1,0,4},
{5,5,5}})
-- displays a small 4-line image at {20,30}, with the pixels
appearing in the same relative positions as the layout
above would indicate
Example Program: see demo\bitmap.ex
See Also: save_image, read_bitmap, display_text_image
─────────────────────────────<display_text_image>───────────────────────────────
Syntax: include image.e
display_text_image(s1, s2)
Description: Display the 2-d sequence of characters and attributes contained
in s2 at line s1[1], column s1[2]. s2 is a sequence of sequences,
where each sequence is a string of characters and attributes to
be displayed. The top-left character is displayed at s1. Other
characters appear to the right or below of this position. The
attributes indicate the foreground and background color of the
preceding character.
Comments: s2 would normally be the result of a previous call to
save_text_image(), although you could construct it yourself.
This routine only works in text modes.
You might use save_text_image/display_text_image in a text-mode
graphical user interface, to allow "pop-up" dialog boxes, and
drop-down menus to appear and disappear without losing what was
previously on the screen.
The sequences of the text image do not have to all be the same
length.
Example: clear_screen()
display_text_image({1,1}, {{'A', WHITE, 'B', GREEN},
{'C', RED+16*WHITE},
{'D', BLUE}})
-- displays: AB
C
D
in the appropriate colors at the top left corner of the screen
See Also: save_text_image, display_image
────────────────────────────────<dos_interrupt>─────────────────────────────────
Syntax: include machine.e
s2 = dos_interrupt(i, s1)
Description: Call DOS software interrupt number i. s1 is a 10-element
sequence of 16-bit register values to be used as input to the
routine. s2 is a similar 10-element sequence containing
output register values after the call returns. machine.e
has the following declaration which shows the order of
the register values in the input and output sequences.
global constant REG_DI = 1,
REG_SI = 2,
REG_BP = 3,
REG_BX = 4,
REG_DX = 5,
REG_CX = 6,
REG_AX = 7,
REG_FLAGS = 8,
REG_ES = 9,
REG_DS = 10
Comments: The register values returned in s2 are always positive values
between 0 and #FFFF (65535).
The flags value in s1[REG_FLAGS] is ignored on input. On output
the least significant bit of s2[REG_FLAGS] has the carry flag,
which usually indicates failure if it is set to 1.
Certain interrupts require that you supply addresses of blocks of
memory. These addresses must be conventional, low-memory
addresses. You can allocate/deallocate low-memory using
allocate_low() and free_low().
With DOS software interrupts you can perform a wide variety
of specialized operations, anything from formatting your
floppy drive to rebooting your computer. For documentation
on these interrupts consult a technical manual such as
Peter Norton's "PC Programmer's Bible", or download Ralf
Brown's Interrupt List from the WEB:
http://www.cs.cmu.edu/afs/cs.cmu.edu/user/ralf/pub/WWW/files.html
Example Program: demo\dosint.ex
See Also: allocate_low, free_low
──────────────────────────────────<draw_line>───────────────────────────────────
Syntax: include graphics.e
draw_line(i, s)
Description: Draw a line connecting two or more points in s, using color i.
Example: draw_line(WHITE, {{100, 100}, {200, 200}, {900, 700}})
This would connect the three points in the sequence using a white
line, i.e. a line would be drawn from {100, 100} to {200, 200}
and another line would be drawn from {200, 200} to {900, 700}.
See Also: polygon, ellipse, pixel
───────────────────────────────────<ellipse>────────────────────────────────────
Syntax: include graphics.e
ellipse(i1, i2, s1, s2)
Description: Draw an ellipse with color i1. The ellipse will neatly fit inside
the rectangle defined by diagonal points s1 {x1, y1} and s2
{x2, y2}. If the rectangle is a square then the ellipse will be a
circle. Fill the ellipse when i2 is 1. Don't fill when i2 is 0.
Example: ellipse(MAGENTA, 0, {10, 10}, {20, 20})
This would make a magenta colored circle just fitting inside the
square: {10, 10}, {10, 20}, {20, 20}, {20, 10}.
Example Program: demo\sb.ex
See Also: polygon, draw_line
─────────────────────────────────────<find>─────────────────────────────────────
Syntax: i = find(x, s)
Description: Find x as an element of s. If successful, return the index
of the first element of s that matches. If unsuccessful
return 0.
Example 1: location = find(11, {5, 8, 11, 2, 3})
-- location is set to 3
Example 2: names = {"fred", "rob", "george", "mary", ""}
location = find("mary", names)
-- location is set to 4
See Also: match, compare
────────────────────────────────────<floor>─────────────────────────────────────
Syntax: x2 = floor(x1)
Description: Return the greatest integer less than or equal to x1. (Round
down to an integer.)
Comments: This function may be applied to an atom or to all elements
of a sequence.
Example: y = floor({0.5, -1.6, 9.99, 100})
-- y is {0, -2, 9, 100}
See Also: remainder
─────────────────────────────────────<free>─────────────────────────────────────
Syntax: include machine.e
free(a)
Description: Free up a previously allocated block of memory by specifying the
address of the start of the block, i.e. the address that was
returned by allocate().
Comments: Use free() to recycle blocks of memory during execution. This
will reduce the chance of running out of memory or getting into
excessive virtual memory swapping to disk. Do not reference
a block of memory that has been freed. When your program
terminates, all allocated memory will be returned to the system.
Do not use free() to deallocate memory that was allocated using
allocate_low(). Use free_low() for this purpose.
Example Program: demo\callmach.ex
See Also: allocate, free_low
───────────────────────────────────<free_low>───────────────────────────────────
Syntax: include machine.e
free_low(i)
Description: Free up a previously allocated block of conventional memory by
specifying the address of the start of the block, i.e. the
address that was returned by allocate_low().
Comments: Use free_low() to recycle blocks of conventional memory during
execution. This will reduce the chance of running out of
conventional memory. Do not reference a block of memory that has
been freed. When your program terminates, all allocated memory
will be returned to the system.
Do not use free_low() to deallocate memory that was allocated
using allocate(). Use free() for this purpose.
Example Program: demo\dosint.ex
See Also: allocate_low, dos_interrupt, free
─────────────────────────────────────<get>──────────────────────────────────────
Syntax: include get.e
s = get(fn)
Description: Read the next string of characters representing a Euphoria object
from file fn, and convert it into the numeric value of that
object. The result s will be a 2-element sequence:
{error status, value}. Error status values are:
GET_SUCCESS -- object was read successfully
GET_EOF -- end of file before object was read
GET_FAIL -- object is not syntactically correct
get() can read arbitrarily complicated Euphoria objects. You
could have a long sequence of values in braces and separated by
commas, e.g. {23, {49, 57}, 0.5, -1, 99, 'A', "john"}. A single
call to get() will read in this entire sequence and return it's
value as a result.
Each call to get() picks up where the previous call left off. For
instance, a series of 5 calls to get() would be needed to read
in:
99 5.2 {1,2,3} "Hello" -1
On the sixth and any subsequent call to get() you would see a
GET_EOF status. If you had something like:
{1,2,xxx}
in the input stream you would see a GET_FAIL error status
because xxx is not a Euphoria object.
Distinct "top-level" objects in the input stream must be
separated from each other with one or more "whitespace"
characters (blank, tab or \n). Whitespace is not necessary
*within* a top-level object.
Comments: The combination of print() and get() can be used to save any
Euphoria object to disk and later read it back. This technique
could be used to implement a database as one or more large
Euphoria sequences stored in disk files. The sequences could be
read into memory, updated and then written back to disk after
each series of transactions is complete.
The value returned is not meaningful unless you have a
GET_SUCCESS status.
Example: Suppose your program asks the user to enter a number from the
keyboard. If he types 77.5, get(0) would return:
{GET_SUCCESS, 77.5}
whereas gets(0) would return
"77.5\n"
Example Program: see demo\mydata.ex.
See Also: print, value, gets, getc
───────────────────────────────<get_active_page>────────────────────────────────
Syntax: include image.e
i = get_active_page()
Description: Some graphics modes on most video cards have multiple pages
of memory. This lets you write screen output to one page
while displaying a different page. get_active_page() returns
the current page number that screen output is being sent to.
Comments: The active and display pages are both 0 by default.
video_config() will tell you how many pages are available in
the current graphics mode.
See Also: set_active_page, get_display_page, video_config
───────────────────────────────<get_display_page>───────────────────────────────
Syntax: include image.e
i = get_display_page()
Description: Some graphics modes on most video cards have multiple pages
of memory. This lets you write screen output to one page
while displaying another. get_display_page() returns the current
page number that is being displayed on the monitor.
Comments: The active and display pages are both 0 by default.
video_config() will tell you how many pages are available in
the current graphics mode.
See Also: set_display_page, get_active_page, video_config
───────────────────────────────────<get_key>────────────────────────────────────
Syntax: i = get_key()
Description: Return the key that was pressed by the user, without waiting for
carriage return. Return -1 if no key was pressed. Special
codes are returned for the function keys, arrow keys etc.
Comments: DOS can hold a small number of key-hits in its keyboard buffer.
get_key() will return the next one from the buffer, or -1 if
the buffer is empty.
Run the key.bat program to see what key code is generated for
each key on your keyboard.
See Also: wait_key, getc
──────────────────────────────────<get_mouse>───────────────────────────────────
Syntax: include mouse.e
x = get_mouse()
Description: Return the last mouse event in the form:
{event, x, y}
or return -1 if there has not been a mouse event since the last
time get_mouse() was called.
Constants have been defined in mouse.e for the possible mouse
events:
global constant MOVE = 1,
LEFT_DOWN = 2,
LEFT_UP = 4,
RIGHT_DOWN = 8,
RIGHT_UP = 16,
MIDDLE_DOWN = 32,
MIDDLE_UP = 64
x and y are the coordinates of the mouse pointer at the time that
the event occurred. get_mouse() returns immediately with either
a -1 or a mouse event. It does not wait for an event to occur.
You must check it frequently enough to avoid missing an event.
When the next event occurs, the current event will be lost, if
you haven't read it. In practice it is not hard to catch almost
all events, and the ones that are lost are usually lost at a
lower level in the system, beyond the control of your program.
Losing a MOVE event is generally not too serious, as the next
MOVE will tell you where the mouse pointer is.
Comments: You need a DOS mouse driver to use this routine.
You can use get_mouse() in most text and graphics modes.
The first call that you make to get_mouse() will turn on a
mouse pointer, or a highlighted character.
In text modes you will probably want to scale the x and y
coordinates to get line and column positions.
DOS generally does not support the use of a mouse in SVGA
graphics modes (beyond 640x480 pixels). This restriction
has been removed in Windows 95 (DOS 7.0).
The x,y coordinate returned could be that of the very tip of the
mouse pointer or might refer to the pixel pointed-to by
the mouse pointer. Test this if you are trying to read the
pixel color using get_pixel. You may have to read x-1,y-1
instead.
Example: a return value of:
{2, 100, 50}
would indicate that the left button was pressed down while the
mouse pointer was at position x=100, y=50 on the screen.
See Also: mouse_events, mouse_pointer
──────────────────────────────────<get_pixel>───────────────────────────────────
Syntax: include graphics.e
x = get_pixel(s)
Description: When s is a 2-element screen coordinate {x, y}, get_pixel()
returns the color of the pixel on the screen at that point.
When s is a 3-element sequence of the form: {x, y, n}
get_pixel() returns a sequence of n color values for the
points starting at {x,y} and moving to the right {x+1,y},
{x+2,y} etc.
Points off the screen have unpredictable color values.
Comments: When n is specified, a very fast algorithm is used to read the
pixel colors on the screen. It is much faster to call get_pixel()
once, specifying a large value of n, than it is to call it many
times, reading one pixel color at a time.
Example: object x
x = get_pixel({30,40})
-- x is set to the color value of point x=30, y=40
x = get_pixel({30,40,100})
-- x is set to a sequence of 100 integer values, representing
-- the colors starting at {30,40} and going to the right
See Also: pixel, graphics_mode, get_position
─────────────────────────────────<get_position>─────────────────────────────────
Syntax: include graphics.e
s = get_position()
Description: Return the current line and column position of the cursor as a
2-element sequence {line, column}.
See Also: position, get_pixel
─────────────────────────────────────<getc>─────────────────────────────────────
Syntax: i = getc(fn)
Description: Get the next character (byte) from file fn. -1 is returned at end
of file.
Comments: File input using getc is buffered, i.e. getc does not actually
go out to the disk for each character. Instead, a large block of
characters will be read in at one time and returned to you one
by one from a memory buffer.
See Also: gets, get_key, wait_key, open
────────────────────────────────────<getenv>────────────────────────────────────
Syntax: x = getenv(s)
Description: Return the value of a DOS environment variable. If the variable
is undefined return -1.
Example: e = getenv("EUDIR")
-- e will be "C:\EUPHORIA" -- or perhaps D:, E: etc.
Comments: Because either a sequence or an atom (-1) might be returned, you
should probably assign the result to a variable declared as
object.
See Also: command_line
─────────────────────────────────────<gets>─────────────────────────────────────
Syntax: x = gets(fn)
Description: Get the next sequence (one line, including '\n') of characters
from file fn. The atom -1 is returned on end of file.
Comments: Because either a sequence or an atom (-1) might be returned, you
should probably assign the result to a variable declared as
object.
The last line in a file might not end with a new-line '\n'
character.
Example:
sequence buffer
object line
-- read a text file into a sequence
buffer = {}
while 1 do
line = gets(0)
if atom(line) then
exit -- end of file
end if
buffer = append(buffer, line)
end while
See Also: getc, puts, open
────────────────────────────────<graphics_mode>─────────────────────────────────
Syntax: include graphics.e
i1 = graphics_mode(i2)
Description: Select graphics mode i2. See graphics.e for a list of valid
graphics modes. If successful, i1 is set to 0, otherwise i1
is set to 1.
Comment: Some modes are referred to as "text" modes because they only
let you display text. Other modes are referred to as "graphics"
modes because you can display pixels, lines, ellipses, etc. and
usually text as well.
As a convenience to your users, it is usually a good idea to
switch back from a pixel graphics mode to the standard text
mode before your program terminates. You can do this with
graphics_mode(-1). If a graphics program leaves your screen
in a mess, you can clear it up with the DOS CLS command, or
by running ex or ed.
Example: if graphics_mode(18) then
puts(SCREEN, "need VGA graphics!\n")
abort(1)
end if
draw_line(BLUE, {{0,0}, {50,50}})
See Also: text_rows, video_config
─────────────────────────────────<int_to_bits>──────────────────────────────────
Syntax: include machine.e
s = int_to_bits(a, i)
Description: Returns the low-order i bits of a, as a sequence of 1's and 0's.
The least significant bits come first. For negative numbers
the two's complement bit pattern is returned.
Comments: You can use subscripting, slicing, and/or/not of entire
sequences etc. to manipulate sequences of bits. Shifting
of bits and rotating of bits are easy to perform.
Example: s = int_to_bits(177, 8)
-- s is {1,0,0,0,1,1,0,1} -- "reverse" order
See Also: bits_to_int, and/or/not of entire sequences in refman.doc
─────────────────────────────────<int_to_bytes>─────────────────────────────────
Syntax: include machine.e
s = int_to_bytes(a)
Description: Convert an integer into a sequence of 4 bytes. These bytes are in
the order expected on the 386+, i.e. least significant byte
first.
Comments: You might use this routine prior to poking the 4 bytes into
memory for use by a machine language program.
The integer can be negative. Negative byte-values will be
returned, but after poking them into memory you will have
the correct (two's complement) representation for the 386+.
Example 1: s = int_to_bytes(999)
-- s is {231, 3, 0, 0}
Example 2: s = int_to_bytes(-999)
-- s is {-231, -4, -1, -1}
See Also: bytes_to_int, int_to_bits, bits_to_int, peek, poke
───────────────────────────────────<integer>────────────────────────────────────
Syntax: i = integer(x)
Description: Return 1 if x is an integer in the range -1073741824 to
+1073741823. Otherwise return 0.
Comments: This serves to define the integer type. You can also call it
like an ordinary function to determine if an object is an
integer.
Example 1: integer z
z = -1
Example 2: if integer(y/x) then
puts(SCREEN, "y is an exact multiple of x")
end if
See Also: atom, sequence, floor
────────────────────────────────────<length>────────────────────────────────────
Syntax: i = length(s)
Description: Return the length of s. s must be a sequence. An error will
occur if s is an atom.
Comments: The length of each sequence is stored internally by the
interpreter for quick access. (In other languages this
operation requires a search through memory for an end marker.)
Example 1: length({{1,2}, {3,4}, {5,6}}) -- 3
Example 2: length("") -- 0
Example 3: length({}) -- 0
─────────────────────────────────────<log>──────────────────────────────────────
Syntax: x2 = log(x1)
Description: Return the natural logarithm of x1.
Comments: This function may be applied to an atom or to all elements
of a sequence. Note that log is only defined for positive
numbers. Your program will abort with a message if you
try to take the log of a negative number or zero.
Example: a = log(100)
-- a is 4.60517
See Also: sin, cos, tan, sqrt
────────────────────────────────────<lower>─────────────────────────────────────
Syntax: include wildcard.e
s2 = lower(s1)
Description: Convert a string of characters to lower case.
Example: s = lower("Euphoria")
-- s is "euphoria"
See Also: upper
─────────────────────────────────<machine_func>─────────────────────────────────
Syntax: x = machine_func(a, x)
Description: see machine_proc() below
─────────────────────────────────<machine_proc>─────────────────────────────────
Syntax: machine_proc(a, x)
Description: Perform a machine-specific operation such as graphics and sound
effects. This routine should normally be called indirectly via
one of the library routines in a Euphoria include file. A direct
call can cause a machine exception if done incorrectly.
See Also: machine_func
────────────────────────────────────<match>─────────────────────────────────────
Syntax: i = match(s1, s2)
Description: Try to match s1 against some slice of s2. If successful, return
the element number of s2 where the (first) matching slice begins,
else return 0.
Example: location = match("pho", "Euphoria")
-- location is set to 3
See Also: find, compare, wildcard_match
─────────────────────────────────<mouse_events>─────────────────────────────────
Syntax: include mouse.e
mouse_events(i)
Description: Use this procedure to select the mouse events that you want
get_mouse() to report. By default, get_mouse() will report all
events. mouse_events() can be called at various stages of the
execution of your program, as the need to detect events changes.
Comments: It is good practice to ignore events that you are not interested
in, particularly the very frequent MOVE event, in order to reduce
the chance that you will miss a significant event.
The first call that you make to mouse_events() will turn on a
mouse pointer, or a highlighted character.
Example: mouse_events(LEFT_DOWN + LEFT_UP + RIGHT_DOWN)
-- will restrict get_mouse() to reporting the left button
being pressed down or released, and the right button
being pressed down. All other events will be ignored.
See Also: get_mouse, mouse_pointer
────────────────────────────────<mouse_pointer>─────────────────────────────────
Syntax: include mouse.e
mouse_pointer(i)
Description: If i is 0 hide the mouse pointer, otherwise turn on the mouse
pointer. Multiple calls to hide the pointer will require
multiple calls to turn it back on. The first call to either
get_mouse() or mouse_events() above, will also turn the pointer
on (once).
Comments: It may be necessary to hide the mouse pointer temporarily when
you update the screen.
See Also: get_mouse, mouse_events
─────────────────────────────────────<open>─────────────────────────────────────
Syntax: fn = open(s1, s2)
Description: Open a file or device, to get the file number. -1 is returned if
the open fails. s1 is the path name of the file or device. s2 is
the mode in which the file is to be opened. Possible modes are:
"r" - open text file for reading
"rb" - open binary file for reading
"w" - create text file for writing
"wb" - create binary file for writing
"u" - open text file for update (reading and writing)
"ub" - open binary file for update
"a" - open text file for appending
"ab" - open binary file for appending
Files opened for read or update must already exist. Files opened
for write or append will be created if necessary. A file opened
for write will be set to 0 bytes. Output to a file opened for
append will start at the end of file.
Output to text files will have carriage-return characters
automatically added before linefeed characters. On input, these
carriage-return characters are removed. A control-Z character
(ASCII 26) will signal an immediate end of file.
I/O to binary files is not modified in any way. Any byte values
from 0 to 255 can be read or written.
Some typical devices that you can open are:
"CON" the console (screen)
"AUX" the serial auxiliary port
"COM1" serial port 1
"COM2" serial port 2
"PRN" the printer on the parallel port
"NUL" a non-existent device that accepts and discards output
Comment: When running under Windows 95, you can open any existing file
that has a long file or directory name in its path (i.e. greater
than the standard DOS 8.3 format) using any open mode - read,
write etc. However, if you try to create a *new* file (open with
"w" or "a" and the file does not already exist) then the name
will be truncated if necessary to an 8.3 style name. We hope to
support creation of new long-filename files in a future release.
Example: integer file_num, file_num95
sequence first_line
constant ERROR = 2
file_num = open("myfile", "r")
if file_num = -1 then
puts(ERROR, "couldn't open myfile\n")
else
first_line = gets(file_num)
end if
-- on Windows 95:
file_num95 = open("bigdirectoryname\\verylongfilename.abcdefg",
"r")
if file_num95 != -1 then
puts(1, "it worked!\n")
end if
See Also: close
───────────────────────────────────<palette>────────────────────────────────────
Syntax: include graphics.e
x = palette(i, s)
Description: Change the color for color number i to s, where s is a sequence
of color intensities: {red, green, blue}. Each value in s can be
from 0 to 63. If successful, a 3-element sequence containing the
previous color for i will be returned, and all pixels on the
screen with value i will be set to the new color. If
unsuccessful, the atom -1 will be returned.
Example:
x = palette(0, {15, 40, 10})
-- color number 0 (normally black) is changed to a shade
of mainly green.
See Also: all_palette
─────────────────────────────────────<peek>─────────────────────────────────────
Syntax: i = peek(a)
or ... s = peek({a, i})
Description: Return a single byte value in the range 0 to 255 from machine
address a, or return a sequence containing i consecutive byte
values starting at address a in memory.
Comments: Since addresses are 32-bit numbers, they can be larger than
the largest value of type integer (31-bits). Variables that
hold an address should therefore be declared as atoms.
It is faster to read several bytes at once using the second
form of peek() than it is to read one byte at a time in a
loop.
Remember that peek takes just one argument, which in the
second form is actually a 2-element sequence.
Example: The following are equivalent:
-- method 1
s = {peek(100), peek(101), peek(102), peek(103)}
-- method 2
s = peek({100, 4})
See Also: poke, allocate, free, allocate_low, free_low, call
────────────────────────────────────<pixel>─────────────────────────────────────
Syntax: include graphics.e
pixel(x, s)
Description: Set one or more pixels starting at point s, where s is a
2-element screen coordinate {x, y}. If x is an atom, one pixel
will be set to the color indicated by x. If x is a sequence then
a number of pixels will be set, starting at s and moving to the
right (increasing x value, same y value).
Comments: When x is a sequence, a very fast algorithm is used to put the
pixels on the screen. It is much faster to call pixel() once,
with a sequence of pixel colors, than it is to call it many
times, plotting one pixel color at a time.
Example 1: pixel(BLUE, {50, 60})
-- the point {50,60} is set to the color BLUE
Example 2: pixel({BLUE, GREEN, WHITE, RED}, {50,60})
-- {50,60} set to BLUE
-- {51,60} set to GREEN
-- {52,60} set to WHITE
-- {53,60} set to RED
See Also: get_pixel, graphics_mode
─────────────────────────────────────<poke>─────────────────────────────────────
Syntax: poke(a, i)
or .. poke(a, s)
Description: First form - Write a single byte value, i, to memory address a.
Second form - Write a sequence of byte values to consecutive
memory locations starting at location a.
Comments: The lower 8-bits of each byte value, i.e. remainder(value, 256),
is actually stored in memory.
It is faster to write several bytes at once using the second
form of poke() than it is to write one byte at a time in a
loop.
Writing to the screen memory with poke() can be much faster than
using puts() or printf(), but the programming is more difficult.
In most cases the speed is not needed. For example, the Euphoria
editor never uses poke().
Example Program: see demo\callmach.ex
See Also: peek, allocate, free, allocate_low, free_low, call
───────────────────────────────────<polygon>────────────────────────────────────
Syntax: include graphics.e
polygon(i1, i2, s)
Description: Draw a polygon with 3 or more vertices given in s, using a
certain color i1. Fill the area if i2 is 1. Don't fill if i2
is 0.
Example: polygon(GREEN, 1, {{100, 100}, {200, 200}, {900, 700}})
-- makes a solid green triangle.
See Also: draw_line, ellipse
───────────────────────────────────<position>───────────────────────────────────
Syntax: position(a1, a2)
Description: Set the cursor to line a1, column a2, where the top left corner
of the screen is line 1, column 1. The next output to the screen
will be printed at this location. position() will report an
error if the location is off the screen.
Comments: The coordinate system for text is different from the one for
graphics. In graphics modes the top-left is (x=0,y=0) and the
first coordinate controls the horizontal, left<-->right location.
Example: position(2,1)
-- the cursor moves to the beginning of the second line from
the top
See Also: get_position, puts, print, printf
────────────────────────────────────<power>─────────────────────────────────────
Syntax: x3 = power(x1, x2)
Description: Raise x1 to the power x2
Comments: The arguments to this functions may be atoms or sequences. The
rules for arithmetic operations on sequences apply.
Powers of 2 are calculated very efficiently.
Example 1: ? power(5, 2)
-- 25 is printed
Example 2: ? power({5, 4, 3.5}, {2, 1, -0.5})
-- {25, 4, 0.534522} is printed
Example 3: ? power(2, {1, 2, 3, 4})
-- {2, 4, 8, 16}
Example 4: ? power({1, 2, 3, 4}, 2)
-- {1, 4, 9, 16}
See Also: log, sqrt
───────────────────────────────────<prepend>────────────────────────────────────
Syntax: s2 = prepend(s1, x)
Description: Prepend x to the start of sequence s1. The length of s2 will be
length(s1) + 1.
Comments: If x is an atom this is the same as s2 = x & s1. If x is a
sequence it is definitely not the same. e.g.
prepend({1,2,3}, {0,0})
-- {{0,0}, 1, 2, 3}
{0,0} & {1,2,3}
-- {0, 0, 1, 2, 3}
The case where s1 and s2 are the same variable is handled
very efficiently.
Example: s = {}
for i = 1 to 10 do
s = prepend(s, i)
end for
-- s is {10,9,8,7,6,5,4,3,2,1}
See Also: append, concatenation (&) and sequence-formation {,,} operators
in refman.doc
────────────────────────────────────<print>─────────────────────────────────────
Syntax: print(fn, x)
Description: Print, to file or device fn, an object x with braces { , , , }
to show the structure.
Comment: If you want to see a string of characters, rather than just the
ASCII codes, you need to use puts or printf.
Example 1: print(1, "ABC") -- output is: {65, 66, 67}
puts(1, "ABC") -- output is: ABC
Example 2: print(1, repeat({10,20}, 3))
-- output is: {{10,20},{10,20},{10,20}}
See Also: ?, puts, printf, get
────────────────────────────────────<printf>────────────────────────────────────
Syntax: printf(fn, st, x)
Description: Print x, to file or device fn, using format string st. If x is
an atom then a single value will be printed. If x is a sequence,
then formats from st are applied to successive elements of x.
Thus printf always takes exactly 3 arguments. Only the length of
the last argument, containing the values to be printed, will
vary. The basic formats are:
%d - print an atom as a decimal integer
%x - print an atom as a hexadecimal integer
%o - print an atom as an octal integer
%s - print a sequence as a string of characters
%e - print an atom as a floating point number with exponential
notation
%f - print an atom as a floating-point number with a decimal
point but no exponent
%g - print an atom as a floating point number using either
the %f or %e format, whichever seems more appropriate
%% - print the '%' character itself
Field widths can be added to the basic formats, e.g. %5d, or
%8.2f. The number before the decimal point is the minimum field
width to be used. The number after the decimal point is the
precision to be used.
If the field width is negative, e.g. %-5d then the value will be
left-justified within the field. Normally it will be right-
justified. If the field width starts with a leading 0, e.g. %08d
then leading zeros will be supplied to fill up the field. If the
field width starts with a '+' e.g. %+7d then a plus sign will be
printed for positive values.
Example 1: rate = 7.875
printf(myfile, "The interest rate is: %8.2f\n", rate)
The interest rate is: 7.88
Example 2: name="John Smith"
score=97
printf(1, "%15s, %5d\n", {name, score})
John Smith, 97
Comments: Watch out for the following common mistake:
printf(1, "%s", name)
This will print only the first character of name, as each element
of name is taken to be a separate value to be formatted. You must
say this instead:
printf(1, "%s", {name})
Now, the third argument of printf is a one-element sequence
containing a single value to be formatted.
See Also: sprintf, puts, open
─────────────────────────────────────<puts>─────────────────────────────────────
Syntax: puts(fn, x)
Description: Output, to file or device fn, a single byte (atom) or sequence
of bytes. The low order 8-bits of each value is actually sent
out. If fn is the screen you will see text characters displayed.
Comment: When you output a sequence of bytes it must not have any
(sub)sequences within it. It must be a sequence of atoms only.
(Typically a string of ASCII codes).
Example 1: puts(SCREEN, "Enter your first name: ")
Example 2: puts(output, 'A') -- the single byte 65 will be sent to output
See Also: printf, gets, open
─────────────────────────────────────<rand>─────────────────────────────────────
Syntax: x2 = rand(x1)
Description: Return a random integer from 1 to x1, where x1 may be from 1 to
the largest positive value of type integer (1073741823).
Comments: This function may be applied to an atom or to all elements
of a sequence.
Example: s = rand({10, 20, 30})
-- s might be: {5, 17, 23} or {9, 3, 12} etc.
See Also: set_rand
─────────────────────────────────<read_bitmap>──────────────────────────────────
Syntax: include image.e
x = read_bitmap(st)
Description: st is the name of a .bmp "bitmap" file. The file should be in
the bitmap format. The most common variations of the format
are supported. If the file is read successfully the result will
be a 2-element sequence. The first element is the palette. The
second element is a 2-d sequence of sequences containing a
graphics-mode image. You can pass the palette to all_palette()
(after dividing it by 4 to scale it). The image can be passed
to display_image().
Bitmaps of 2,4,16 or 256 colors are supported. If the file is
not in a good format an error code (atom) is returned instead:
global constant BMP_OPEN_FAILED = 1,
BMP_UNEXPECTED_EOF = 2,
BMP_UNSUPPORTED_FORMAT = 3
Comments: You can create your own bitmap picture files using Windows
Paintbrush and many other graphics programs. You can then
incorporate these pictures into your Euphoria programs.
Example: x = read_bitmap("c:\\windows\\arcade.bmp")
-- note: double backslash needed to get single backslash in
a string
Example Program: demo\bitmap.ex
See Also: palette, display_image
──────────────────────────────────<remainder>───────────────────────────────────
Syntax: x3 = remainder(x1, x2)
Description: Compute the remainder after dividing x1 by x2. The result will
have the same sign as x1, and the magnitude of the result will
be less than the magnitude of x2.
Comments: The arguments to this function may be atoms or sequences. The
rules for arithmetic operations on sequences apply.
Example 1: a = remainder(9, 4)
-- a is 1
Example 2: s = remainder({81, -3.5, -9, 5.5}, {8, -1.7, 2, -4})
-- s is {1, -0.1, -1, 1.5}
Example 3: s = remainder({17, 12, 34}, 16)
-- s is {1, 12, 2}
Example 4: s = remainder(16, {2, 3, 5})
-- s is {0, 1, 1}
────────────────────────────────────<repeat>────────────────────────────────────
Syntax: s = repeat(x, a)
Description: Create a sequence of length a where each element is x.
Comments: When you repeat a sequence or a floating-point number the
interpreter does not actually make multiple copies in memory.
Rather, a single copy is "pointed to" a number of times.
Example 1: repeat(0, 10) -- {0,0,0,0,0,0,0,0,0,0}
Example 2: repeat("JOHN", 4) -- {"JOHN", "JOHN", "JOHN", "JOHN"}
See Also: append, prepend, sequence-formation operator in refman.doc
──────────────────────────────────<save_image>──────────────────────────────────
Syntax: include image.e
s3 = save_image(s1, s2)
Description: Save a rectangular image from a graphics screen. The result
is a 2-d sequence of sequences containing all the pixels
in the image. You can redisplay the image using display_image().
s1 is a 2-element sequence {x1, y1} specifying the top-left
pixel in the image. s2 is a sequence {x2, y2} specifying the
bottom-right pixel.
Comments: You might use this in a graphical user interface to save a
portion of the screen before you display a drop-down menu
or dialog box.
Example: s = save_image({0,0}, {50,50})
display_image({100,200}, s)
display_image({300,400}, s)
-- saves a 51x51 square image, then redisplays it at {100,200}
-- and at {300,400}
See Also: display_image, save_text_image
───────────────────────────────<save_text_image>────────────────────────────────
Syntax: include image.e
s3 = save_text_image(s1, s2)
Description: Save a rectangular region of text from a text-mode screen.
The result is a sequence of sequences containing ASCII characters
and attributes from the screen. You can redisplay this text using
display_text_image(). s1 is a 2-element sequence {line1, column1}
specifying the top-left character. s2 is a sequence
{line2, column2} specifying the bottom right character.
Comments: Because the character attributes are also saved, you will get
the correct foreground and background color for each character
if you redisplay the text.
This routine only works in text modes.
You might use this function in a text-mode graphical user
interface to save a portion of the screen before displaying a
drop-down menu, dialog box, alert box etc.
If you are flipping video pages, note that this function reads
from the current active page.
Example: If the top 2 lines of the screen have:
Hello
World
s = save_text_image({1,1}, {2,5})
Then s is something like:
{"H-e-l-l-o-",
"W-o-r-l-d-"}
where we have indicated the attribute bytes by '-'
See Also: display_text_image, save_image, set_active_page
────────────────────────────────────<scroll>────────────────────────────────────
Syntax: include graphics.e
scroll(i1, i2, i3)
Description: Scroll a region of text on the screen either up (i1 positive) or
down (i1 negative) by i1 lines. The region is the series of lines
on the screen from i2 (top line) to i3 (bottom line), inclusive.
A new blank line will appear at the top or bottom.
Example Program: see bin\ed.ex
See Also: clear_screen, text_rows
─────────────────────────────────────<seek>─────────────────────────────────────
Syntax: include file.e
i1 = seek(fn, i2)
Description: Seek (move) to any byte position in the file fn or to the end of
file if i2 is -1. For each open file there is a current byte
position that is updated as a result of I/O operations on the
file. The initial file position is 0 for files opened for read,
write or update. The initial position is the end of file for
files opened for append. The value returned by seek() is 0 if the
seek was successful, and non-zero if it was unsuccessful. It is
possible to seek past the end of a file. In this case undefined
bytes will be added to the file to make it long enough for the
seek.
See Also: where, open
───────────────────────────────────<sequence>───────────────────────────────────
Syntax: i = sequence(x)
Description: Return 1 if x is a sequence else return 0.
Comments: This serves to define the sequence type. You can also call
it like an ordinary function to determine if an object is
a sequence.
Example 1:
sequence s
s = {1,2,3}
Example 2:
if sequence(x) then
sum = 0
for i = 1 to length(x) do
sum = sum + x[i]
end for
else
-- x must be an atom
sum = x
end if
See Also: atom, object type in refman.doc
───────────────────────────────<set_active_page>────────────────────────────────
Syntax: include image.e
set_active_page(i)
Description: Select video page i to send all screen output to.
Comments: With multiple pages you can instantaneously change the entire
screen without causing any visible "flicker". You can also
save the screen and bring it back quickly.
video_config() will tell you how many pages are available in
the current graphics mode.
By default, the active page and the display page are both 0.
This works under DOS, or full-screen under Windows. In a
partial-screen window you cannot change the active page.
Example: include image.e
-- active & display pages are initially both 0
puts(1, "\nThis is page 0\n")
set_active_page(1) -- screen output will now go to page 1
clear_screen()
puts(1, "\nNow we've flipped to page 1\n")
if getc(0) then -- wait for key-press
end if
set_display_page(1) -- "Now we've ..." becomes visible
if getc(0) then -- wait for key-press
end if
set_display_page(0) -- "This is ..." becomes visible again
set_active_page(0)
See Also: get_active_page, set_display_page
──────────────────────────────<set_display_page>────────────────────────────────
Syntax: include image.e
set_display_page(i)
Description: Set video page i to be mapped to the visible screen.
Comments: With multiple pages you can instantaneously change the entire
screen without causing any visible "flicker". You can also
save the screen and bring it back quickly.
video_config() will tell you how many pages are available in
the current graphics mode.
By default, the active page and the display page are both 0.
This works under DOS, or full-screen under Windows. In a
partial-screen window you cannot change the active page.
Example: See set_active_page example.
See Also: get_display_page, set_active_page
──────────────────────────────────<set_rand>────────────────────────────────────
Syntax: include machine.e
set_rand(i)
Description: Set the random number generator to a certain state, i, so that
you will get a known series of random numbers on subsequent
calls to rand().
Comments: Normally the numbers returned by the rand() function are totally
unpredictable, and will be different each time you run your
program. Sometimes however you may wish to repeat the same
series of numbers, perhaps because you are trying to debug
your program, or maybe you want the ability to generate the
same output (e.g. a random picture) for your user upon request.
Example: sequence s, t
s = repeat(0, 3)
t = s
set_rand(12345)
s[1] = rand(10)
s[2] = rand(100)
s[3] = rand(1000)
set_rand(12345) -- same value for set_rand()
t[1] = rand(10) -- same arguments to rand() as before
t[2] = rand(100)
t[3] = rand(1000)
-- at this point s and t will be identical
See Also: rand
─────────────────────────────────────<sin>──────────────────────────────────────
Syntax: x2 = sin(x1)
Description: Return the sine of x1, where x1 is in radians.
Comments: This function may be applied to an atom or to all elements
of a sequence.
Example: sin_x = sin({.5, .9, .11})
-- sin_x is {.479, .783, .110}
See Also: cos, tan
─────────────────────────────────────<sort>─────────────────────────────────────
Syntax: include sort.e
s2 = sort(s1)
Description: Sort s1 into ascending order using a fast sorting algorithm. The
elements of s1 can be any mix of atoms or sequences. Atoms come
before sequences, and sequences are sorted "alphabetically" where
the first elements are more significant than the later elements.
Comments: By defining your own compare function to override the built-in
compare(), you can change the ordering of values from sort(), and
perhaps choose a field or element number on which to base the
sort. Define your compare() as a global function before
including sort.e.
Example 1: x = 0 & sort({7,5,3,8}) & 0
-- x is set to {0, 3, 5, 7, 8, 0}
Example 2: y = sort({"Smith", "Jones", "Doe", 5.5, 4, 6})
-- y is {4, 5.5, 6, "Doe", "Jones", "Smith"}
Example 3: database = sort({{"Smith", 95.0, 29},
{"Jones", 77.2, 31},
{"Clinton", 88.7, 44}})
-- The 3 database "records" will be sorted by the first "field"
-- i.e. by name. Where the first field (element) is equal it
-- will be sorted by the second field etc.
-- database is {{"Clinton", 88.7, 44},
{"Jones", 77.2, 31},
{"Smith", 95.0, 29}}
See Also: compare, match, find
────────────────────────────────────<sound>─────────────────────────────────────
Syntax: sound(i)
Description: Turn on the PC speaker at frequency i. If i is 0 the speaker
will be turned off.
Example: sound(1000) -- starts a fairly high pitched sound
───────────────────────────────────<sprintf>────────────────────────────────────
Syntax: s = sprintf(st, x)
Description: This is exactly the same as printf(), except that the output
is returned as a sequence of characters, rather than being
sent to a file or device. st is a format string, x is the
value or sequence of values to be formatted. printf(fn, st, x)
is equivalent to puts(fn, sprintf(st, x)).
Comments: Some typical uses of sprintf are:
1. Converting numbers to strings.
2. Creating strings to pass to system().
3. Creating formatted error messages and passing them to
a common error message handler.
Example: s = sprintf("%08d", 12345)
-- s is "00012345"
See Also: printf, value, get
─────────────────────────────────────<sqrt>─────────────────────────────────────
Syntax: x2 = sqrt(x1)
Description: Calculate the square root of x1.
Comments: This function may be applied to an atom or to all elements
of a sequence.
Taking the square root of a negative number will abort your
program with a run-time error message.
Example: r = sqrt(16)
-- r is 4
See Also: log, power
────────────────────────────────────<system>────────────────────────────────────
Syntax: system(s, a)
Description: Pass a command string s to the DOS command interpreter for
execution. The argument a indicates the manner in which to
return from the system call.
value of a return action
---------- -------------
0 - restore previous graphics mode
(clears the screen)
1 - make a beep sound, wait for a
key press, then restore the
graphics mode
2 - do not restore graphics mode
Comments: Action 2 should only be used when it is known that the system
call will not change the graphics mode.
You can use Euphoria as a sophisticated DOS "batch" language
by making calls to system().
A Euphoria program will start off using extended memory. If
extended memory runs out the program will consume conventional
memory. If conventional memory runs out it will use virtual
memory, i.e. swap space on disk. The DOS command run by system()
will fail if there is not enough conventional memory available.
To avoid this situation you can reserve some conventional (low)
memory by typing:
SET CAUSEWAY=LOWMEM:xxx
where xxx is the number of K of conventional memory to reserve.
Type this before running your program. You can also put this in
a .bat file that runs your program, or in AUTOEXEC.BAT. For
example:
SET CAUSEWAY=LOWMEM:80
ex myprog.ex
This will reserve 80K of conventional memory, which should be
enough to run simple DOS commands like COPY, MOVE, MKDIR etc.
Example: system("copy temp.txt a:\\temp.bak", 2)
-- note use of double backslash in literal string to get
single backslash
Example Program: see install.ex
See Also: dir, current_dir, getenv, command_line
─────────────────────────────────────<tan>──────────────────────────────────────
Syntax: x2 = tan(x1)
Description: Return the tangent of x1, where x1 is in radians.
Comments: This function may be applied to an atom or to all elements
of a sequence.
Example: t = tan(1.0)
-- t is 1.55741
See Also: sin, cos
──────────────────────────────────<text_color>──────────────────────────────────
Syntax: include graphics.e
text_color(i)
Description: Set the foreground text color. Add 16 to get blinking text
in some modes. See graphics.e for a list of possible colors.
Comments: Text that you print *after* calling text_color will have the
desired color.
When your program terminates, the last color that you selected
and actually printed on the screen will remain in effect.
Thus you may have to print something, maybe just '\n', in
WHITE to restore white text, especially if you are at the
bottom line of the screen, ready to scroll up.
Example: text_color(BRIGHT_BLUE)
See Also: bk_color
──────────────────────────────────<text_rows>───────────────────────────────────
Syntax: include graphics.e
i2 = text_rows(i1)
Description: Set the number of lines of text on the screen to i1 if possible.
i2 will be set to the actual new number of lines.
Comments: Values of 25, 28, 43 and 50 lines are supported by most graphics
cards.
See Also: graphics_mode
─────────────────────────────────────<time>─────────────────────────────────────
Syntax: a = time()
Description: Return the number of seconds since some fixed point in the past.
The resolution on MS-DOS is about 0.05 seconds.
Comments: Take the difference between two readings of time(), to
measure, for example, how long a section of code takes to
execute.
Example: constant ITERATIONS = 1000000
integer p
atom t0, loop_overhead
t0 = time()
for i = 1 to ITERATIONS do
end for
loop_overhead = time() - t0
t0 = time()
for i = 1 to ITERATIONS do
p = power(2, 20)
end for
? (time() - t0 - loop_overhead)/ITERATIONS
-- calculates time (in seconds) for one call to power
See Also: date
────────────────────────────────────<trace>─────────────────────────────────────
Syntax: with trace
trace(x)
Description: If x is 1 or 2 then turn on full-screen statement tracing. If x
is 0 then turn off tracing. When x is 2 a monochrome trace
display is forced on. Tracing only occurs in subroutines that
were compiled when "with trace" was in effect. See the section
on Debugging in refman.doc.
Comments: Use trace(2) if the color display is hard to view on your system.
Example: if x < 0 then
-- ok, here's the case I want to debug...
trace(1)
-- etc.
...
end if
See Also: Chapter 3 in refman.doc.
────────────────────────────────────<upper>─────────────────────────────────────
Syntax: include wildcard.e
s2 = upper(s1)
Description: Convert a string of characters to upper case.
Example: s = upper("Euphoria")
-- s is "EUPHORIA"
See Also: lower
──────────────────────────────────<use_vesa>────────────────────────────────────
Syntax: include machine.e
use_vesa(i)
Description: use_vesa(1) will force Euphoria to use the VESA graphics
standard. This may cause Euphoria programs to work better
in SVGA graphics modes with certain graphics cards.
use_vesa(0) will restore Euphoria's original method of
using the graphics card.
Comments: Most people can ignore this. However if you experience
difficulty in SVGA graphics modes you should try calling
use_vesa(1) at the start of your program before any calls
to graphics_mode().
Arguments to use_vesa() other than 0 or 1 should not be used.
Example: use_vesa(1)
fail = graphics_mode(261)
See Also: graphics_mode
────────────────────────────────────<value>─────────────────────────────────────
Syntax: include get.e
s = value(st)
Description: Read the string representation of a Euphoria object, and compute
the value of that object. A 2-element sequence,
{error_status, value} is actually returned, where error_status
can be one of:
GET_SUCCESS -- a valid object representation was found
GET_EOF -- end of string reached too soon
GET_FAIL -- syntax is wrong
Comments: This works the same as get(), but it reads from a string
that you supply, rather than from a file or device.
Example 1: s = value("12345"}
-- s is {GET_SUCCESS, 12345}
Example 2: s = value("{0, 1, -99.9}")
-- s is {GET_SUCCESS, {0, 1, -99.9}}
Example 3: s = value("+++")
-- s is {GET_FAIL, 0}
See Also: get, sprintf, print
─────────────────────────────────<video_config>─────────────────────────────────
Syntax: include graphics.e
s = video_config()
Description: Return a sequence of values describing the current video
configuration:
{color monitor?, graphics mode, text rows, text columns,
xpixels, ypixels, number of colors, number of pages}
The following constants are defined in graphics.e:
global constant VC_COLOR = 1,
VC_MODE = 2,
VC_LINES = 3,
VC_COLUMNS = 4,
VC_XPIXELS = 5,
VC_YPIXELS = 6,
VC_NCOLORS = 7,
VC_PAGES = 8
Comments: This routine makes it easy for you to parameterize a program
so it will work in many different graphics modes.
On the PC there are two types of graphics mode. The first type
lets you print text only. The second type lets you plot pixels,
or points, in various colors. The second type also usually lets
you print text. You can tell that you are in a purely text mode,
because the VC_XPIXELS and VC_YPIXELS fields will be 0.
Library routines such as polygon, draw_line, and ellipse only
work in a pixel mode.
Example: vc = video_config() -- in mode 3 with 25-lines of text:
-- vc is {1, 3, 25, 80, 0, 0, 32, 8}
See Also: graphics_mode
──────────────────────────────────<wait_key>────────────────────────────────────
Syntax: include get.e
i = wait_key()
Description: Return the next key pressed by the user. Don't return until
a key is pressed.
Comments: You could achieve the same result using get_key() as follows:
while 1 do
k = get_key()
if k != -1 then
exit
end if
end while
However, on multi-tasking systems like Windows, Windows NT,
or OS/2 this "busy waiting" would slow the system down.
wait_key() lets the operating system do other useful work
while your program is waiting for the user to press a key.
You could also use getc(0), assuming file number 0 was input
from the keyboard, except that you wouldn't pick up the special
codes for function keys, arrow keys etc.
See Also: get_key, getc
────────────────────────────────────<where>─────────────────────────────────────
Syntax: include file.e
i = where(fn)
Description: This function returns the current byte position in the file fn.
This position is updated by reads, writes and seeks on the file.
It is the place in the file where the next byte will be read
from, or written to.
See Also: seek, open
────────────────────────────────<wildcard_file>─────────────────────────────────
Syntax: include wildcard.e
i = wildcard_file(s1, s2)
Description: Return 1 (TRUE) if the filename s2 matches the wild card pattern
s1. Return 0 (FALSE) otherwise. This is similar to DOS wildcard
matching, but better in some cases. * matches any 0 or more
characters, ? matches any single character. Character comparisons
are not case sensitive.
Comments: You might use this function to check the output of the dir()
routine for file names that match a pattern supplied by the
user of your program.
In DOS "*ABC.*" will match ALL files. wildcard_file("*ABC.*", s)
will only match when the file name part has "ABC" at the end
(as you would expect).
Example 1: i = wildcard_file("AB*CD.?", "aB123cD.e")
-- i is set to 1
Example 2: i = wildcard_file("AB*CD.?", "abcd.ex")
-- i is set to 0, because the file type has 2 letters not 1
Example Program: see bin\search.ex
See Also: wildcard_match, dir
────────────────────────────────<wildcard_match>────────────────────────────────
Syntax: include wildcard.e
i = wildcard_match(s1, s2)
Description: This function performs general matching of a string against a
pattern containing * and ? wildcards. It returns 1 (TRUE) if
string s2 matches pattern s1. It returns 0 (FALSE) otherwise.
* matches any 0 or more characters. ? matches any
single character. Character comparisons are case sensitive.
Comments: If you want case insensitive comparisons, pass both s1 and s2
through upper(), or both through lower() before calling
wildcard_match().
If you want to detect a pattern anywhere within a string,
add * to each end of the pattern:
i = wildcard_match('*' & pattern & '*', string)
There is currently no way to treat * or ? literally in a pattern.
Example 1: i = wildcard_match("A?B*", "AQBXXYY")
-- i is 1 (TRUE)
Example 2: i = wildcard_match("*xyz*", "AAAbbbxyz")
-- i is 1 (TRUE)
Example 3: i = wildcard_match("A*B*C", "a111b222c")
-- i is 0 (FALSE) because upper/lower case doesn't match
Example Program: see bin\search.ex
See Also: wildcard_file, match, upper, lower, compare
─────────────────────────────────────<wrap>─────────────────────────────────────
Syntax: include graphics.e
wrap(i)
Description: Allow text to wrap at the right margin (i = 1) or get truncated
(i = 0).
Comments: By default text will wrap.
Example: puts(1, repeat('x', 100) & "\n\n")
-- now have a line of 80 'x' followed a line of 20 more 'x'
wrap(0)
puts(1, repeat('x', 100) & "\n\n")
-- creates just one line of 80 'x'
See Also: puts, position